Almathera Ten Pack 3: CDPD 3

home *** CD-ROM | disk | FTP | other *** search

/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / ab20 / unarced / utilities / system / intuition / shadow / docs / shadowlibfuncs.doc < prev next >

Wrap

Text File | 1995-03-17 | 12.2 KB | 441 lines

Shadow.lib Documentation Library Version 4.6 By David Navas Updated: 05 Feb 1992 Copyright © 1992 by David Navas All Rights Reserved All functions except for SPrintfCallback take their arguments on the stack. NAME CreateInstance -- Creates in instance of a class. SYNOPSIS object = CreateInstance( pClass, className, metaName, ..., METHOD_END) d0 < args on stack > FUNCTION Creates an instance of the described class. Classes may be either a private class, a public class, or a public meta. If pClass is non-NULL, then that class is used to create the instance. If metaName is NULL, then the className is used as a name for the meta stored on the ShadowBase->sb_metaTree (which is what will be used to create the instance). Otherwise the metaName is used as the name of the meta and className is used as the name for a class on the meta's ATTR_OBJECTLIST tree which is the class that it will use to create the instance. The arguments are the arguments that are passed to the METHOD_META_INIT method of the object that is created. Complicated? Three possibilities: CreateInstance(myPrivateClass, NULL, NULL, lots-of-args, METHOD_END); - creates instance of myPrivateClass CreateInstance(NULL, METACLASS, NULL, lots-of-args, METHOD_END); - creates a Class whose class is METACLASS CreateInstance(NULL, ROOTCLASS, METACLASS, lots-f-args, METHOD_END); - creates an instance of ROOTCLASS, where ROOTCLASS is a class found in the METACLASS' ATTR_OBJECTLIST. INPUTS META pClass; - a pointer to the private class that you want an instance of. If NULL, then use the className and metaName to find a public class. char *className; - the name of the public class. char *metaName; - the name of the public meta that the class can be found in. If NULL, then the className is treated as the name of a public meta that you want an instance of. . . <--- other arguments . OUTPUTS void *object; - the instance, or the return value from the METHOD_META_INIT of the particular class. As the programmer, you may want to change what that method returns. For all included classes, the METHOD_META_INIT returns the object. NULL if error (for instance, class could not be found). RESULT A new Instance is formed. BUGS none known. NOTES SEE ALSO METHOD_META_CREATE method in ShadowLibraryMethods.doc CreateSubClass() RemoveObject() NAME CreateSubClass -- Creates a sub-class of a class. SYNOPSIS object = CreateSubClass( pClass, className, metaName, ..., METHOD_END) d0 < args on stack > FUNCTION Creates a subclass of the described class. Classes may be either a private class, a public class, or a public meta. If pClass is non-NULL, then that class is used to create the subclass. If metaName is NULL, then the className is used as a name for the meta stored on the ShadowBase->sb_metaTree (which is what will be used to create the submeta). Otherwise the metaName is used as the name of the meta and className is used as the name for a class on the meta's ATTR_OBJECTLIST tree which is the class that it will use to create the subclass. The arguments are the arguments that are passed to the METHOD_META_SUB method of the class that is being sub-classed. Complicated? Three possibilities: CreateSubClass(myPrivateClass, NULL, NULL, lots-of-args, METHOD_END); - creates subclass of myPrivateClass CreateSubClass(NULL, METACLASS, NULL, lots-of-args, METHOD_END); - creates a Meta as a submeta of METACLASS CreateSubClass(NULL, ROOTCLASS, METACLASS, lots-f-args, METHOD_END); - creates a subclass of ROOTCLASS, where ROOTCLASS is a class found in the METACLASS' ATTR_OBJECTLIST. INPUTS META pClass; - a pointer to the private class that you want a subclass of. If NULL, then use the className and metaName to find a public class. char *className; - the name of the public class. char *metaName; - the name of the public meta that the class can be found in. If NULL, then the className is treated as the name of a public meta that you want a subclass of. . . <--- other arguments . OUTPUTS void *object; - the subclass, or the return value from the METHOD_META_SUB of the particular class. As the programmer, you may want to change what that method returns. For all included classes, the METHOD_META_SUB returns the class. NULL if error (for instance, class could not be found). RESULT A new subclass is formed. BUGS none known. NOTES SEE ALSO METHOD_META_SUB method in ShadowLibraryMethods.doc CreateInstance() RemoveObject() NAME DoJazzMethod -- Front-end to DJM() [shadow.lib] SYNOPSIS result = DoJazzMethod( object, class, method, ..., METHOD_END) d0 < args on stack > FUNCTION This function is the front-end to DJM(). It checks for a valid object, and returns NULL if none. If there is no valid class, class is set to object->cob_class. Then, DJM() is called via: DJM(&object, SHADOW_MSG_FINDMETHOD) INPUTS OBJECT object; - the object to send the method to. If NULL, function returns NULL META class; - the first "class" to check for the method. This allows you to send a method to the superClass... if NULL, class is set to object->cob_class. char *method; - pointer to the method string. . . <--- other arguments . OUTPUTS void *result; - result from DJM() RESULT BUGS none known. NOTES SEE ALSO DJM() NAME GetObject -- Semaphored access to an object in a public area. SYNOPSIS object = GetObject( OBJECT *objectPtr ) d0 FUNCTION In some attributes, there may be object pointers that you need to retrieve from that attribute. On the other hand, somebody else might change it at the same time. This function uses the ShadowBase->sb_strSemaphore to protect the access to the objectPtr. The object that is returned is returned Use()'d, so when you are done with the object you should call DropObject(object) on it. INPUTS OBJECT *objectPtr; - the pointer to the structure element that holds the object pointer you want. OUTPUTS void *object; - the object that *objectPtr points to. RESULT BUGS none known. NOTES SEE ALSO SetObject() NAME HandleMessages -- Handle all incoming SHADOW messages, return when ^C is hit. SYNOPSIS HandleMessages( struct Task *task ) FUNCTION Handle all incoming messages in the ATTR_JAZZPROCESS' jp_port and jp_replyPort, and return when a ^C is sensed. In order to correctly Wait for ^C, when a Signal is detected, all messages are first added to a list, then all the message are handled by taking them off the list and calling either ParseJazzMethod (for jp_port) or JunkIPCMessage (for jp_replyPort). INPUTS struct Task *task; - optional current task pointer. If NULL, then function calls FindTask(NULL). OUTPUTS RESULT When the function returns, there was a ^C sensed. BUGS none known. NOTES SEE ALSO ParseJazzMessage() JunkIPCMessage() NAME PSemString -- used to ensure single-thread startup. SYNOPSIS PSemString( char *string, long semFlags ) FUNCTION Does the following: PSem(UseString(string), semFlags); The SWRI examples uses this function to ensure that only a single copy of the executable is running. INPUTS char *string; - the system string equivalent which is used to semaphore thread startup. long semFlags; - the flags to send to PSem(). OUTPUTS none. RESULT BUGS none known. NOTES SEE ALSO VSemString() PSem()/VSem() NAME RemoveObject -- send a METHOD_META_REMOVE to an object. SYNOPSIS RemoveObject( OBJECT object ) FUNCTION Does a: DoJazzMethod(object, NULL, METHOD_META_REMOVE, METHOD_END); INPUTS OBJECT object; - the object to send the Remove method to. OUTPUTS none. RESULT BUGS none known. NOTES SEE ALSO CreateInstance() CreateSubClass() NAME SetObject -- Semaphored access to an object in a public area. SYNOPSIS oldObject = GetObject( OBJECT *objectPtr , OBJECT newObject ) d0 FUNCTION In some attributes, there may be object pointers that you need to change in that attribute. On the other hand, somebody else might retrieve it at the same time. This function uses the ShadowBase->sb_strSemaphore to protect the access to the objectPtr. The object that is returned is returned Use()'d, so when you are done with the object you should call DropObject(object) on it. The old value that was stored at the objectPtr address is returned as oldObject and replaced by newObject. The newObject is TRANSFERRED to the address, so if you want to maintain a valid pointer in newObject when GetObject() returns, call this function like this: oldObject = GetObject(objectPtr, UseObject(newObject)); If you don't care about the returned object, you should call the function like this: DropObject(GetObject(objectPtr, newObject)); INPUTS OBJECT *objectPtr; - the pointer to the structure element that holds the object pointer you want. OBJECT newObject; - object to transfer into the objectPtr. OUTPUTS void *object; - the object that *objectPtr points to. RESULT BUGS none known. NOTES SEE ALSO GetObject() NAME SprintfCallback -- sprintf callback for RawDoFmt. [shadow.lib] SYNOPSIS SprintfCallback(c, text); d0 a3 FUNCTION This function performs the parsing RawDoFmt requires for an sprintf() type function. INPUTS char c; - the character to insert char *text; - the string to insert it into. OUTPUTS a3 pointer is incremented RESULT BUGS none known. NOTES SEE ALSO NAME VSemString -- used to ensure single-thread startup. SYNOPSIS VSemString( char *string ) FUNCTION Does the following: VSem(FindString(string), semFlags); DropString(string); The SWRI examples uses this function to ensure that only a single copy of the executable is running. INPUTS char *string; - the system string equivalent which is used to semaphore thread startup. OUTPUTS none. RESULT BUGS none known. NOTES SEE ALSO PSemString() PSem()/VSem()